package org.stars.daostars.starterkit;


/**
 * E' l'interfaccia di base dei moduli DAO.
 * Ogni modulo che si occupa della persistenza dei dati
 * dovrebbe implentare almeno questa interfaccia. L'implementazione di questa
 * interfaccia non esclude l'impiego di ulteriori metodi per il collegamento
 * alla base dati.
 * 
 * Tutti i metodi di questa interfaccia possono generare delle eccezioni che
 * vengono passate ai metodi invocanti.
 * 
 * I metodi possono essere suddivisi per finalit�. 
 * 
 * <h2>Inserimento</h2>
 * <ul>
 * 	<li><b>crea(EntityBean entity)</b>: crea un entityBean. I suoi attributi vengono
 * specificati mediante lo stesso entityBean. L'id nella maggiorparte dei casi non
 * ha necessit� di essere definito in input, ma verr� definito nel momento stesso
 * in cui ho eseguito l'inserimento nel database.</li>
 * </ul>
 * 
 * <h2>Aggiorna</h2>
 * <ul>
 * <li><b>aggiorna(EntityBean entity)</b>: aggiorna un entityBean mediante comando update.
 * I parametri dell'istruzione SQL vengono ricavati direttamente dall'entity.</li>
 * </ul>
 * 
 * <h2>Recupera</h2>
 * <ul>
 * <li><b>recupera()</b>: recupera l'intero elenco degli entity bean presenti nel db.</li>
 * <li><b>recupera(long id)</b>: recupera un singolo entity a partire dal suo id.</li>
 * <li><b>recupera(EntityBean entity)</b>: recupera un entityBean.
 * I parametri del recupero vengono ricavati direttamente dall'entity.</li>
 * </ul>
 * 
 * <h2>Elimina</h2>
 * <ul>
 * <li><b>elimina(long id)</b>: cancella un entityBean mediante il suo id.</li>
 * </ul>
 * 
 * @author Alex Svetina (908303)
 * @author Francesco Benincasa (908099)
 * @version 1.0
 * @param <E> 
 * 
 */
public interface Dao<E extends EntityBeanBase> {		
	/**
	 * Crea un entityBean. I suoi attributi vengono
	 * specificati mediante lo stesso entityBean. L'id nella maggiorparte dei casi non
	 * ha necessit� di essere definito in input, ma verr� definito nel momento stesso
	 * in cui ho eseguito l'inserimento nel database.
	 * <p>
	 * <b>Precondizioni</b>: l'entity bean passato come parametro deve essere valorizzati
	 * tutti gli attributi. L'attributo <code>Id</code> non viene letto ma viene modificato
	 * dal metodo.
	 * <p>
	 * <b>Postcondizioni</b>: l'entity bean passato come parametro ha tutti i campi valorizzati,
	 * compreso l'<code>Id</code> che contiene il valore della chiave primaria che � stata
	 * appena inserita. In caso di errore, viene generata un'eccezione. In caso di esito
	 * positivo dell'operazione il metodo restituisce <code>true</code>.
	 * <p>
	 * @param entity elemento da inserire
	 * @return <i>true</i> se l'inserimento � andato a buon fine.
	 * @throws Exception Nel caso in cui ci sia qualche problema con il codice sql.
	 */
	boolean crea(E entity) throws Exception;
	
	
	/**
	 * Recupera un elenco di bean in base alle condizioni specificate nel bean passato
	 * come parametro del metodo. L'ordine degli entity bean
	 * pu� essere definito mediante il metodo <code>OrderBy</code>.
	 * <p>
	 * <b>Precondizioni</b>: -
	 * <p>
	 * <b>Postcondizioni</b>: l'elenco risultato dell'operazione di recupera si trova
	 * nell'attributo <code>ElencoBean</code>. Il primo elemento viene collocato anche
	 * nel metodo <code>DettaglioBean</code>. Nel caso di errore viene sollevata un'eccezione.
	 * <p>
	 * @param entity bean
	 * @return restituisce il numero di elementi recuperati.
	 * @throws Exception Nel caso in cui ci sia qualche problema con il codice sql.
	 */
	int recupera(E entity) throws Exception;
	
	/**
	 * Aggiorna un entityBean mediante comando update.
	 * @param entity entity da modificare.
	 * @return restituisce true se l'operazione � andato a buon fine.
	 * @throws Exception Nel caso in cui ci sia qualche problema con il codice sql.
	 */
	int aggiorna(E entity) throws Exception;
	
	
	/**
	 * Cancella un entityBean. I vari parametri di cancellazione vengono passati
	 * come parametri.
	 * 
	 * @param entity bean che contiene i parametri di cancellazione
	 * @return
	 * 		restituisce <code>true</code> se l'operazione � andata a buon fine,
	 * 		<code>false</code> altrimenti.
	 * @throws Exception sql
	 */
	int elimina(E entity) throws Exception;
}
